The section describes the programming interface of the UART Peripheral driver. More...

Data Structures
struct	uart_state_t
	Runtime state of the UART driver. More...

struct	uart_user_config_t
	User configuration structure for UART driver. More...

UART Driver
uart_status_t	uart_init (uint32_t uartInstance, uart_state_t uartState, const uart_user_config_t uartUserConfig)
	This function initializes a UART instance for operation. More...

uart_status_t	uart_send_data (uart_state_t uartState, const uint8_t sendBuffer, uint32_t txByteCount, uint32_t timeout)
	This function sends (transmits) data out through the UART module using a blocking method. More...

uart_status_t	uart_send_data_async (uart_state_t uartState, const uint8_t sendBuffer, uint32_t txByteCount)
	This function sends (transmits) data through the UART module using a non-blocking method. More...

uart_status_t	uart_get_transmit_status (uart_state_t uartState, uint32_t bytesTransmitted)
	This function returns whether the previous UART transmit has finished. More...

uart_status_t	uart_get_receive_status (uart_state_t uartState, uint32_t bytesReceived)
	This function returns whether the previous UART receive is complete. More...

void	uart_shutdown (uart_state_t *uartState)
	This function shuts down the UART by disabling interrupts and the transmitter/receiver. More...

uart_status_t	uart_receive_data (uart_state_t uartState, uint8_t rxBuffer, uint32_t requestedByteCount, uint32_t timeout)
	This function gets (receives) data from the UART module using a blocking method. More...

uart_status_t	uart_receive_data_async (uart_state_t uartState, uint8_t rxBuffer, uint32_t requestedByteCount)
	This function gets (receives) data from the UART module using a non-blocking method. More...

uart_status_t	uart_abort_sending_data (uart_state_t *uartState)
	This function terminates an asynchronous UART transmission early. More...

uart_status_t	uart_abort_receiving_data (uart_state_t *uartState)
	This function terminates an asynchronous UART receive early. More...

UART Peripheral Driver

Overview

The UART peripheral driver is used to transfer data to and from external devices on the Universal Asynchronous Receiver/Transmitter (UART) serial bus. It provides a way to transmit and receive buffers of data with a single function call.

Device structs

The driver uses an instantiation of the uart_state_t structure to maintain the current state of a particular UART instance module driver. This struct holds data that are used by the UART peripheral driver to communicate between the transmit and receive transfer functions and the interrupt handler. The interrupt handler also uses this information to keep track of its progress. Because the driver itself does not statically allocate memory, the caller provides memory for the driver state structure during init. The user is only responsible to pass in the memory for this run-time state structure where the UART driver will take care of filling out the members.

User config structs

The UART driver uses instances of the user configuration structure uart_user_config_t for the UART driver. This allows you to configure the most common settings of the UART with a single function call. Settings include: UART baud rate; UART parity mode: disabled (default), or even or odd; the number of stop bits; the number of bits per data word.

Initialization

To initialize the UART driver, call uart_init() and pass the instance number of the UART peripheral you want to use, memory for the run-time state structure, and a pointer to the user configuration structure. For example, to use UART0 pass a value of 0 to the init function. Then, memory for the run-time state structure. Finally, pass a user configuration structure of the type uart_user_config_t as shown here:

// UART configuration structure for user
typedef struct UartUserConfig {
    uint32_t baudRate;            
    uart_parity_mode_t parityMode;     
    uart_stop_bit_count_t stopBitCount; 
    uart_bit_count_per_char_t bitCountPerChar; 
} uart_user_config_t;

Typically, uart_user_config_t instantiation is configured as 8-bit-char, no-parity, 1-stop-bit (8-n-1) with a 9600 bps baud rate. uart_user_config_t instantiation can be easily modified to configure the UART peripheral either to a different baud rate or character transfer features. This is an example code to set up a user UART configuration instantiation:

uart_user_config_t uartConfig;
uartConfig.baudRate = 9600;
uartConfig.bitCountPerChar = kUart8BitsPerChar;
uartConfig.parityMode = kUartParityDisabled;
uartConfig.stopBitCount = kUartOneStopBit;

This is an example of how to make the uart_init() function call given the user configuration structure previously given, as well as for UART instance 0.

uint32_t uartInstance = 0;
uart_state_t uartState; // user provides memory for the driver state structure
uart_init(uartInstance, &uartConfig, &uartState);

Transfers

The driver implements transmit and receive functions to transfer buffers of data. The driver also supports two different modes for transferring data: blocking and non-blocking.The blocking transmit and receive functions are uart_send_data() and uart_receive_data().The non-blocking (async) transmit and receive functions are uart_send_data_async() and uart_receive_data_async().In all cases mentioned here, the functions are interrupt driven.The following code examples show how to use the aforementioned functions. First, it is assumed that the UART module has been initialized as described previously in the Initialization section.For blocking transfer functions transmit and receive:

uint8_t sourceBuff[26] ={0}; // sourceBuff can be filled out with desired data
uint8_t readBuffer[10] = {0}; // readBuffer gets filled with uart_receive_data function
uint32_t byteCount = sizeof(sourceBuff);
uint32_t readByteCount = sizeof(readBuffer);
// for each use there, set timeout as "1"
// uartState is the run-time state. Pass in memory for this 
// declared previously in the initialization section
uart_send_data(&uartState, sourceBuff, byteCount, 1); // function won't return until transmit is complete
uart_receive_data(&uartState, readBuffer, 1, timeoutValue); // function won't return until it receives all data

For non-blocking (async) transfer functions transmit and receive:

uint8_t *pTxBuff;
uint8_t rxBuff[10];
uint32_t txCurrentByteCount, readByteCount;
// assume pTxBuff and txCurrentByteCount have been initialized
uart_send_data_async(&uartState, pTxBuff, txCurrentByteCount);
// now check on status of transmit and wait until done, the code can do something else and 
// check back later, this is just an example
while (uart_get_transmit_status(&uartState, &bytesTransmittedCount) == kStatus_UART_TxBusy);
// for receive, assume rxBuff is set up to receive data and readByteCount is initialized
uart_receive_data_async(&uartState, rxBuff, readByteCount);
// now check on status of receive and wait until done, the code can do something else and 
// check back later, this is just an example
while (uart_get_receive_status(&uartState, &bytesReceivedCount) == kStatus_UART_RxBusy);

Data Structure Documentation

struct uart_state_t

This struct holds data that are used by the UART peripheral driver to communicate between the transfer function and the interrupt handler. The interrupt handler also uses this information to keep track of its progress. The user is only responsible to pass in the memory for this run-time state structure where the UART driver will take care of filling out the members.

Data Fields
uint32_t	instance
	UART module instance number. More...

volatile bool	isTransmitInProgress
	True if there is an active transmit. More...

bool	isTransmitAsync
	Whether the transmit is asynchronous or not. More...

const uint8_t *	sendBuffer
	The buffer of data being sent. More...

volatile size_t	remainingSendByteCount
	The remaining number of bytes to be transmitted. More...

volatile size_t	transmittedByteCount
	Number of bytes transmitted so far. More...

volatile bool	isReceiveInProgress
	True if there is an active receive. More...

bool	isReceiveAsync
	Whether the receive is asynchronous or not. More...

uint8_t *	receiveBuffer
	The buffer of received data. More...

volatile size_t	remainingReceiveByteCount
	The remaining number of bytes to be received. More...

volatile size_t	receivedByteCount
	Number of bytes received so far. More...

sync_object_t	txIrqSync
	Used to wait for ISR to complete its TX business. More...

sync_object_t	rxIrqSync
	Used to wait for ISR to complete its RX business. More...

uint8_t	txFifoEntryCount
	Number of data word entries in TX FIFO. More...

Field Documentation

uint32_t uart_state_t::instance

volatile bool uart_state_t::isTransmitInProgress

bool uart_state_t::isTransmitAsync

const uint8_t* uart_state_t::sendBuffer

volatile size_t uart_state_t::remainingSendByteCount

volatile size_t uart_state_t::transmittedByteCount

volatile bool uart_state_t::isReceiveInProgress

bool uart_state_t::isReceiveAsync

uint8_t* uart_state_t::receiveBuffer

volatile size_t uart_state_t::remainingReceiveByteCount

volatile size_t uart_state_t::receivedByteCount

sync_object_t uart_state_t::txIrqSync

sync_object_t uart_state_t::rxIrqSync

uint8_t uart_state_t::txFifoEntryCount

struct uart_user_config_t

Use an instance of this struct with uart_init(). This allows you to configure the most common settings of the UART peripheral with a single function call. Settings include: UART baud rate; UART parity mode: disabled (default), or even or odd; the number of stop bits; the number of bits per data word.

Data Fields
uint32_t	baudRate
	UART baud rate.

uart_parity_mode_t	parityMode
	parity mode, disabled (default), even, odd

uart_stop_bit_count_t	stopBitCount
	number of stop bits, 1 stop bit (default) or 2 stop bits

uart_bit_count_per_char_t	bitCountPerChar
	number of bits, 8-bit (default) or 9-bit in a word (up to 10-bits in some UART instances)

Function Documentation

uart_status_t uart_init	(	uint32_t	uartInstance,
		uart_state_t *	uartState,
		const uart_user_config_t *	uartUserConfig
	)

This function will initialize the run-time state structure to keep track of the on-going transfers, ungate the clock to the UART module, initialize the module to user defined settings and default settings, configure the IRQ state structure and enable the module-level interrupt to the core, and enable the UART module transmitter and receiver. The following is an example of how to set up the uart_state_t and the uart_user_config_t parameters and how to call the uart_init function by passing in these parameters:

uart_user_config_t uartConfig;
uartConfig.baudRate = 9600;
uartConfig.bitCountPerChar = kUart8BitsPerChar;
uartConfig.parityMode = kUartParityDisabled;
uartConfig.stopBitCount = kUartOneStopBit;
uart_state_t uartState;
uart_init(uartInstance, &uartState, &uartConfig);

Parameters

uartInstance	The UART module instance number.
uartState	A pointer to the UART driver state structure memory. The user is only responsible to pass in the memory for this run-time state structure where the UART driver will take care of filling out the members. This run-time state structure keeps track of the current transfer in progress.
uartUserConfig	The user configuration structure of type uart_user_config_t. The user is responsbile to fill out the members of this structure and to pass the pointer of this struct into this function.

Returns: An error code or kStatus_UART_Success.

uart_status_t uart_send_data	(	uart_state_t *	uartState,
		const uint8_t *	sendBuffer,
		uint32_t	txByteCount,
		uint32_t	timeout
	)

A blocking (also known as synchronous) function means that the function does not return until the transmit is complete. This blocking function is used to send data through the UART port.

Parameters

uartInstance	The UART module instance number.
sendBuffer	A pointer to the source buffer containing 8-bit data chars to send.
txByteCount	The number of bytes to send.
timeout	A timeout value for RTOS abstraction sync control in milli-seconds (ms).

Returns: An error code or kStatus_UART_Success.

uart_status_t uart_send_data_async	(	uart_state_t *	uartState,
		const uint8_t *	sendBuffer,
		uint32_t	txByteCount
	)

A non-blocking (also known as synchronous) function means that the function returns immediately after initiating the transmit function. The application has to get the transmit status to see when the transmit is complete. In other words, after calling non-blocking (asynchronous) send function, the application must get the transmit status to check if transmit is completed or not. The asynchronous method of transmitting and receiving allows the UART to perform a full duplex operation (simultaneously transmit and receive).

Parameters

uartState	A pointer to the UART driver state structure.
sendBuffer	A pointer to the source buffer containing 8-bit data chars to send.
txByteCount	The number of bytes to send.

Returns: An error code or kStatus_UART_Success.

uart_status_t uart_get_transmit_status	(	uart_state_t *	uartState,
		uint32_t *	bytesTransmitted
	)

When performing an async transmit, the user can call this function to ascertain the state of the current transmission: in progress (or busy) or complete (success). In addition, if the transmission is still in progress, the user can obtain the number of words that have been currently transferred.

Parameters

uartState	A pointer to the UART driver state structure.
bytesTransmitted	A pointer to a value that is filled in with the number of bytes that are sent in the active transfer.

Return values

kStatus_UART_Success	The transmit has completed successfully.
kStatus_UART_TxBusy	The transmit is still in progress. bytesTransmitted is filled with the number of bytes which are transmitted up to that point.

uart_status_t uart_get_receive_status	(	uart_state_t *	uartState,
		uint32_t *	bytesReceived
	)

When performing an async receive, the user can call this function to ascertain the state of the current receive progress: in progress (or busy) or complete (success). In addition, if the receive is still in progress, the user can obtain the number of words that have been currently received.

Parameters

uartState	A pointer to the UART driver state structure.
bytesReceived	A pointer to a value that is filled in with the number of bytes which are received in the active transfer.

Return values

kStatus_UART_Success	The receive has completed successfully.
kStatus_UART_RxBusy	The receive is still in progress. bytesReceived is filled with the number of bytes which are received up to that point.

void uart_shutdown ( uart_state_t * uartState )

This function disables the UART interrupts, disables the transmitter and receiver, and flushes the FIFOs (for modules that support FIFOs).

Parameters

uartState A pointer to the UART driver state structure.

uart_status_t uart_receive_data	(	uart_state_t *	uartState,
		uint8_t *	rxBuffer,
		uint32_t	requestedByteCount,
		uint32_t	timeout
	)

A blocking (also known as synchronous) function means that the function does not return until the receive is complete. This blocking function is used to send data through the UART port.

Parameters

uartState	A pointer to the UART driver state structure.
rxBuffer	A pointer to the buffer containing 8-bit read data chars received.
requestedByteCount	The number of bytes to receive.
timeout	A timeout value for RTOS abstraction sync control in milli-seconds (ms).

Returns: An error code or kStatus_UART_Success.

uart_status_t uart_receive_data_async	(	uart_state_t *	uartState,
		uint8_t *	rxBuffer,
		uint32_t	requestedByteCount
	)

A non-blocking (also known as synchronous) function means that the function returns immediately after initiating the receive function. The application has to get the receive status to see when the receive is complete. In other words, after calling non-blocking (asynchronous) get function, the application must get the receive status to check if receive is completed or not. The asynchronous method of transmitting and receiving allows the UART to perform a full duplex operation (simultaneously transmit and receive).

Parameters

uartState	A pointer to the UART driver state structure.
rxBuffer	A pointer to the buffer containing 8-bit read data chars received.
requestedByteCount	The number of bytes to receive.

Returns: An error code or kStatus_UART_Success.

uart_status_t uart_abort_sending_data ( uart_state_t * uartState )

During an async UART tranmission, the user has the option to terminate the transmission early if the transmission is still in progress.

Parameters

uartState A pointer to the UART driver state structure.

Return values

kStatus_UART_Success	The transmit was succesful.
kStatus_UART_NoTransmitInProgress	No transmission is currently in progress.

uart_status_t uart_abort_receiving_data ( uart_state_t * uartState )

During an async UART receive, the user has the option to terminate the receive early if the receive is still in progress.

Parameters

uartState A pointer to the UART driver state structure.

Return values

kStatus_UART_Success	The receive was succesful.
kStatus_UART_NoTransmitInProgress	No receive is currently in progress.

Data Structures

UART Driver

UART Peripheral Driver

Overview

Device structs

User config structs

Initialization

Transfers

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Function Documentation